package jbitarrays.api;

import javax.annotation.concurrent.NotThreadSafe;

/**
 * An abstraction over either persistent or in-memory bit storage. It represents
 * memory as an infinite, zero-indexed bit array.
 * 
 * @since 1.0
 */
@NotThreadSafe public interface InfiniteBitArray {
	/**
	 * Gets the index'th bit of the array.
	 * 
	 * @throws IllegalArgumentException
	 *             if {@code index} is less than zero.
	 * @return <code>true</code> if the index'th bit of the array is a one and
	 *         <code>false</code> otherwise.
	 * @since 1.0
	 */
	public boolean get(int index) throws IllegalArgumentException;

	/**
	 * Sets the index'th bit of the array.
	 * 
	 * @param value
	 *            <code>true</code> to set the index'th bit of the array to a
	 *            one and <code>false</code> to set it to a zero.
	 * @throws IllegalArgumentException
	 *             if {@code index} is less than zero.
	 * @since 1.0
	 */
	public void set(int index, boolean value) throws IllegalArgumentException;

	/**
	 * Utility method for bulk access.
	 * 
	 * @return the next {@code howMany} bits in the lowest order bits of an int.
	 * @throws IllegalArgumentException
	 *             if {@code index} is less than zero or {@code howMany} is less
	 *             than zero or greater than {@link Integer#SIZE}.
	 * @since 1.0
	 */
	public int getN(int index, int howMany) throws IllegalArgumentException;

	/**
	 * Utility method for bulk access.
	 * 
	 * @param value
	 *            the {@code howMany} lowest order bits of this int will be set
	 *            in this bit array.
	 * @throws IllegalArgumentException
	 *             if {@code index} is less than zero or {@code howMany} is less
	 *             than zero or greater than {@link Integer#SIZE}.
	 * @since 1.0
	 */
	public void setN(int index, int howMany, int value) throws IllegalArgumentException;
}
